/*
 * Copyright (C) 2010 TopCoder Inc., All Rights Reserved.
 */
package com.hercules.xre.protocol.testing;

/**
 * <p>
 * This interface defines the API contract for a protocol testing connection manager to be able to handle events and
 * commands. The manager will facilitate the communication between a client and the ApplicationManager it is
 * aggregated to via the ApplicationManagerAware contract it extends. It will handle the sending of commands from this
 * ApplicationManager to the client, and it will pass events from the client to the ApplicationManager via the
 * configured EventHandler.
 * </p>
 *
 * <p>
 * Note that different from ConnectionManager, the XRE commands are represented as Strings instead of XRECommand's in
 * ProtocolTestingConnectionManager.
 * </p>
 *
 * <p>
 * <strong>Thread-safety:</strong> Implementations will need to be effectively thread-safe.
 * </p>
 *
 * @author TCSDESIGNER, TCSDEVELOPER
 * @version 1.0
 */
public interface ProtocolTestingConnectionManager {
    /**
     * <p>
     * Accepts the given event handler that this connection manager can pass events to. This method is expected to be
     * called only once during its lifetime.
     * </p>
     *
     * @param eventHandler the event handler that should be used to inform application about communication events,
     *        can't be null
     *
     * @throws ProtocolTestingConnectionManagerException If there is an error while setting the EventHandler
     * @throws IllegalArgumentException if eventHandler is null.
     */
    public void startAcceptingConnections(EventHandler eventHandler)
        throws ProtocolTestingConnectionManagerException;

    /**
     * <p>
     * Sends the command.
     * </p>
     *
     * @param sessionGUID GUID of a session, can't be null/empty
     * @param command command that should be sent, can't be null/empty
     *
     * @throws ProtocolTestingConnectionManagerException If there is an error while sending the command
     * @throws IllegalArgumentException if any parameter is invalid.
     */
    public void sendCommand(String sessionGUID, String command)
        throws ProtocolTestingConnectionManagerException;

    /**
     * <p>
     * Disposes this manager.
     * </p>
     *
     * @throws ProtocolTestingConnectionManagerException if any error occurs while disposing the connection manager.
     */
    public void dispose() throws ProtocolTestingConnectionManagerException;
}
